home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / amok_lha / amok69.lha / AMOK-Poster next >
Text File  |  1993-08-15  |  8KB  |  160 lines
  1. ===========================================================================
  2.                AMOK - Amiga Modula & Oberon Klub  Stuttgart
  3.  
  4.           "AMOK-Poster": Norm bzw. Standardform für AMOK-Beiträge
  5.                Tips und Anhaltspunkte für Veröffentlichungen
  6. ===========================================================================
  7.  
  8. Einleitung
  9.  
  10. Wir  -AMOK-  sind  gerne  bereit,  auch  anderen  Modula-2-  bzw.   Oberon-
  11. Programmierern  mit  den  AMOK-Disks  einen  Weg zur Veröffentlichung Ihrer
  12. Programme  zu  bieten.   Ziel unserer PD-Reihe ist es schließlich, für eine
  13. möglichst  weite  Verbreitung von Modula & Oberon zu sorgen.  Da sich diese
  14. Programmiersprachen optimal zum Austausch von Programm-Modulen eignen, kann
  15. jeder  Programmierer  hierzu beitragen.  Je größer die Modulbibliothek ist,
  16. auf die ein Programmierer zurückgreifen kann, desto weniger muß er sich mit
  17. zeitraubenden Alltagsproblemen herumschlagen und sozusagen "das Rad zweimal
  18. erfinden".   Falls Sie also Module geschrieben haben, von denen Sie denken,
  19. daß  auch  andere  sie  gebrauchen  können, schicken Sie sie an AMOK.  Wenn
  20. irgend  möglich werden wir den Beitrag in unsere AMOK-Reihe aufnehmen.  Wir
  21. stellen  zwar  keine  Ansprüche  an die Genialität der Programme, damit Ihr
  22. Beitrag  eine  Chance  hat,  veröffentlicht zu werden, sollten Sie aber die
  23. unten  aufgeführten  Punkte  beachten.   Damit  gewährleistet ist, daß Ihre
  24. PD-Software auch wirklich brauchbar ist.
  25.  
  26.  
  27. 1) Kriterien
  28.  
  29. Wie  schon erwähnt stellen wir keine Anforderungen an das, was ein Programm
  30. besonderes  kann.   Das  was  es  kann,  soll  es aber sinnvoll und korrekt
  31. ausführen.   Ein  simples  aber  nützliches Modul hat, auch wenn es noch so
  32. banal ist, höhere Chancen, veröffentlicht zu werden, als ein Riesenprojekt,
  33. das an sich genial ist, aber ständig guru-meditiert.
  34.  
  35.  
  36. 2) AMOK Anforderungen
  37.  
  38. Die   Folgenden   Punkte   sind  verbindlich  und  von  jedem  AMOK-Beitrag
  39. einzuhalten:
  40.  
  41. * Zu  jedem  Modul(-packet)  gehört eine Dokumentation.  Ohne Dokumentation
  42.   sind  die  Module für andere unbrauchbar.  Es gibt auf den AMOK-Disketten
  43.   folgende Formen der Dokumentation:
  44.  
  45.     - Dokumentation  im Klartext in einer extra Datei mit der Endung ".dok"
  46.       (für deutsche Dokumentation) oder ".doc" (für die englische)
  47.     - stichwortartige  Kurzbeschreibung  der Prozeduren im Definitionsmodul
  48.       Diese  Form  der  Dokumentation  ist auf AMOK# >= 25 bei "HeaderInfo"
  49.       genauer beschrieben.
  50.   Die Dokumentation sollte mindestens diese Informationen beinhalten:
  51.     - Bedeutung und Auswirkung der Prozedurparameter
  52.     - Funktion und Verwendungszweck der Prozeduren
  53.     - Bedeutung der Rückgabewerte der Prozeduren
  54.     - Wichtige Hinweise über exportierte Variablen, Konstanten und Typen
  55.     - Hinweise auf mögliche Fehler (soweit bekannt)
  56.     - Angaben über eventuelle Einschränkungen oder Warnungen
  57.   Wenn  möglich  sollte die Dokumentation nur aus reinem ASCII-Code und nur
  58.   mit   den   ANSI  Steuersequenzen  geschrieben  werden.   (MuchMore-  und
  59.   copy-to-prt:-verträglich)
  60.  
  61. * Der  Source-Code  sollte den Modulen immer beigefügt werden.  Schließlich
  62.   sollen  andere  Programmierer  aus  Ihrem  Programm  etwas lernen können.
  63.   Außerdem  ist  es somit möglich, eventuelle Fehler zu verbessern oder das
  64.   Programm  an  eigene Bedürfnisse anzupassen.  Als Ausnahmen sind folgende
  65.   zulässig:
  66.     - das  Programm ist wirklich ausgesprochen genial und gehört eigentlich
  67.       patentiert (es muß natürlich absolut fehlerfrei sein)
  68.     - die  Module  sind  Teile  eines  von  Ihnen  kommerziell vertriebenen
  69.       Programms, und Sie wollen nicht, daß jemand Einblick erhält
  70.     - Ihr  Programmierstil  ist  so  schlecht  und  Ihre  Methoden so haar-
  71.       sträubend,  daß  Sie  den  Source-Code  niemandem  zumuten wollen (In
  72.       diesem  Fall  sollten  Sie  sich  allerdings  Überlegen, ob Sie nicht
  73.       lieber C oder Assembler programmieren wollen)
  74.  
  75. * Definitions  und  Implementationsmodul  sollten  unseren Modulkopf (siehe
  76.   "HeaderInfo")  beinhalten.   Dieser  ist  zur  leichteren  Verwaltung der
  77.   inzwischen    mehrere    Megabyte   umfassenden   AMOK-Softwarebibliothek
  78.   notwendig.   Bitte  erfindet  keine  eigenen  ShortCuts!   Diese sind den
  79.   Klubmitgliedern  vorenthalten!   Haltet  Euch an unsere Formatvorgaben in
  80.   "HeaderInfo".
  81.  
  82. * Alle  Dateien und Unterdirectories sollen Icons haben, so daß Sie von der
  83.   Workbench  aus zugänglich sind.  Das Default-Tool von Textdateien (Source
  84.   und Dokumentation) muß auf ":c/MuchMore" eingestellt sein.
  85.  
  86.  
  87. 3) AMOK Vereinbarungen
  88.  
  89. Es wird gebeten, auch auf folgendes zu achten:
  90.  
  91. * Sollten  zum  Compilieren  eines  Moduls noch andere nicht standardmäßige
  92.   Module  benötigt  werden,  sollten  diese mitgeliefert werden.  Dabei ist
  93.   darauf  zu  achten,  daß  die  sym-Schlüssel stimmen, d.h.  alles mit der
  94.   selben  Version  der  Definitionsmodule compiliert wurde.  Existieren von
  95.   imortierten   Modulen  mehrere  Versionen,  dann  ist  anzugeben,  welche
  96.   benötigt wird. (Vermerk :Imports.)
  97.  
  98. * Im  Source-Code  und  in  der  Dokumentation  sollte man wenn möglich die
  99.   Zeilenlänge  auf  70  bis  75  Zeichen  begrenzen.   MuchMore und M2Emacs
  100.   akzeptieren  zwar  80  Zeichen, viele möchten jedoch sicherlich die Texte
  101.   ausdrucken, und da ist ein Rand ganz nützlich.
  102.  
  103. * Prozedur-,    Variablen-,   Konstanten-   und   Typenbezeichner   sollten
  104.   vorzugsweise englisch sein, ebenso die Kurzbeschreibung der Prozeduren im
  105.   Definitionsmodul (siehe AMOK#7, ProgInfo/StandardIDs).
  106.   Wenigstens  sollte  man  Englisch  und  Deutsch  nicht mischen.  Deutsche
  107.   Dokumentation sollte nicht fehlen, englische ist freiwillig.
  108.  
  109. * Kleine  Demoprogramme  dienen der leichteren Verständnis und dem besseren
  110.   Einarbeiten  in  die  Funktionen  eines Moduls.  Oft sind Testmodule oder
  111.   sonstige  Beispielanwendungen als Nebenprodukte eigener Programme sowieso
  112.   vorhanden.
  113.  
  114. * Seien  Sie  fair  gegenüber  anderen Programmierern.  Public Domain heißt
  115.   noch lange nicht "Software-Freiwild".  Wenn Sie Programmteile von anderen
  116.   übernehmen,   erwähnen   Sie   den  Autor  bitte  im  Modulkopf  oder  in
  117.   Kommentarzeilen.    Für   eine  kommerzielle  Nutzung  brauchen  Sie  die
  118.   Schriftliche  Erlaubnis  des  jewiligen Autors.  Denken Sie bitte auch an
  119.   eventuelle Shareware-Gebühren.
  120.  
  121.  
  122. 4) Zum Thema korrekte Programme
  123.  
  124. Die  folgenden Anweisungen gelten nicht speziell für AMOK-Disketten sondern
  125. sollten  von  allen  Programmierern beachtet werden.  Wenn diese Punkte für
  126. Sie noch nicht selbstverständlich sind, empfehlen wir Ihnen DRINGENDST Ihre
  127. Programme in Zukunft dementsprechend auszulegen.
  128.  
  129. * Alle  Programme  sollten  auf  korrektem Weg verlassen werden können, das
  130.   heißt,  ohne  neu  starten zu müssen, und so, daß uneingeschränkt weiter-
  131.   gearbeitet  werden  kann.   Außerdem  sollen  Sie alle Betriebsmittel und
  132.   Resourcen  an  das  System  zurückgeben  (Speicher deallozieren, Fenster,
  133.   Screens und Files schließen).
  134.  
  135. * Programme  sollten sich nicht so verhalten, als wären Sie die einzigen im
  136.   System,  sondern  auf  das Multitasking und seine Restriktionen Rücksicht
  137.   nehmen   (z.B.    gegenseitiger   Ausschluß   beim  Zugriff  auf  System-
  138.   strukturen).
  139.  
  140. * Programme  sollen  sich  gegenüber  dem Benutzer logisch und bei Fehlein-
  141.   gaben robust verhalten.
  142.  
  143. * Man sollte nie davon ausgehen, immer alle Betriebsmittel zu bekommen, die
  144.   man  anfordert.   Programme  sollen  sich  definiert verhalten, wenn z.B.
  145.   Files  nicht  geöffnet  werden  können, oder nicht mehr genügend Speicher
  146.   vorhanden ist.
  147.  
  148. * Die  Benutzerschnittstelle  soll den beim AMIGA allgemein üblichen Richt-
  149.   linien entsprechen (siehe Intuition Reference Manual Chapter 12:  Style).
  150.  
  151. * Programme   sollten  wenn  möglich  keine  spezielle  Gerätekonfiguration
  152.   vorraussetzen.
  153.  
  154. * Besonders  für die Entwicklung zukünftiger Bibliotheksmodule ist wichtig,
  155.   daß  die  Prozeduren  reentrant  sind,  falls  es  sinnvoll  ist, sie von
  156.   mehreren  Tasks  aus  gleichzeitig zu benutzen (es ist in Modula ja nicht
  157.   möglich, Module zweimal zu importieren).
  158.  
  159. --- Viel Spaß
  160.